Angular-GraphQL cookbook by Urigo · Pull Request #3135 · angular/angular.io

Urigo · 2017-01-25T02:06:31Z

Hello!

This PR is for an Angular & GraphQL cookbook and includes everything an Angular developer needs in order to integrate GraphQL into their Angular apps.

It includes:

Full cookbook of how to use GraphQL in your Angular app
Full Clone of Tour Of Heroes last chapter with in-memory-graphql instead of on-memory REST
All Tests pass both for JIT and AOT
Working Plunker
Green Lint
We've also updated a lot of libraries during that process to be compatible with Rollup and AOT
apollo-client
apollo-client-rxjs
apollo-angular (and renaming from angular2-apollo #JustAngular)
GraphQL-js

I believe I’ve followed all the guidelines needed but I’m also here in SF for 2 weeks if you need me to come over for a review!

kamilkisiela · 2017-01-26T11:25:04Z

Soooooooooooooo awesome!

DxCx · 2017-01-26T11:41:04Z

Cool!! :)

alonp99 · 2017-01-29T08:48:38Z

Good job!

Urigo · 2017-02-03T09:51:32Z

Updated and rebased to latest master and included the changes made on these PRs:

All the tests of my PR passes but the tests for the server-communication example are failing..
@wardbell I've checked out master (without my changes) locally and the tests are failing as well.
Also I've looked at the deployed version here - https://angular.io/docs/ts/latest/guide/server-communication.html
Opened the live example in Plunker and it failed as well (changed the Wikipedia url inside the example to https to overcome another problem and then got the one the is happening also in the build).
This is weird because I can see that CI was passing in the last commit to master.
Just to be completely sure I also clone the angular.io master on another machine and had the same error.
I can maybe try to solve it but I'm not sure I want to change your examples as part of this PR, maybe as part of another one.
What would you suggest?
Thanks

Urigo · 2017-02-03T10:23:30Z

ohhh just spotted this and that
good to know I'm not crazy :)

googlebot · 2017-02-07T04:35:30Z

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that they're okay with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

googlebot · 2017-02-07T04:35:30Z

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that they're okay with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

kapunahelewong

Thanks for the changes. It's looking great. I've made a few comments.

kapunahelewong · 2017-02-01T15:12:51Z

public/docs/ts/latest/cookbook/graphql.jade

+
+.l-sub-section
+  :marked
+    You can think about it as a replacement/enhancement for REST (but you can use them both alongside each other)


Add period.

kapunahelewong · 2017-02-07T15:37:06Z

public/docs/ts/latest/cookbook/graphql.jade

+
+  Apollo's `mutate` function returns the result as an Observable.
+  The Observable returns a `mutationResult` variable that is structured 
+  like the `ApolloQueryResult` Typescript Type, where the generic `T` type is a `Hero` type:


Typescript Type -> TypeScript type

Please change globally from Typescript to TypeScript.

kapunahelewong · 2017-02-07T15:41:16Z

public/docs/ts/latest/cookbook/graphql.jade

+    networkStatus: NetworkStatus;
+  };
+:marked
+  and that's also how you reference that result variable in Typescript.


Start a new sentence. How about:

If this looks familiar, it's because that's also how you reference the _____ variable in TypeScript.

Please be sure to specify the variable (sometimes a word like "that" can be vague).

kapunahelewong · 2017-02-07T15:49:30Z

public/docs/ts/latest/cookbook/graphql.jade

+  };
+:marked
+  and that's also how you reference that result variable in Typescript.
+  So in order the get the actual hero data being returned, you access those values like so:


How about (or something like - we just need to streamline it and state exactly what we are doing):

To access the hero data the ______ returns, use dot notation to traverse the mutationResult and assign it to a _____.

I don't know the exact words that should go in the blanks.

kapunahelewong · 2017-02-07T15:51:41Z

public/docs/ts/latest/cookbook/graphql.jade

+  So in order the get the actual hero data being returned, you access those values like so:
+makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'access-mutation-result', 'heroes.component.ts')
+:marked
+  and then push them into the `heroes` array.


Once you have access to the data, push them into the heroes array.

We want a complete sentence here.

kapunahelewong · 2017-02-07T16:26:52Z

public/docs/ts/latest/cookbook/graphql.jade

+:marked
+  Now create a new `networkInterface` class and call it `InBrowserNetworkInterface`.
+
+  That class will have a `schema` property which it will initialize in the constructor.


~~That~~

This class initializes a schema property in the constructor.

kapunahelewong · 2017-02-07T16:31:25Z

public/docs/ts/latest/cookbook/graphql.jade

+  That class will have a `schema` property which it will initialize in the constructor.
+
+  Then create a `query` function that will recieve a query as a variable and execute that query using
+  `graphql` execute function against the schema property.


How about this:

Next, the query function takes as an argument the request, or query, and executes that query using the GraphQL execute function against the schema property.

Took almost as is but changed a small thing. let me know if that makes sense

kapunahelewong · 2017-02-07T16:35:30Z

public/docs/ts/latest/cookbook/graphql.jade

+  `graphql` execute function against the schema property.
+
+  You send empty objects to the `rootValue` and `contextValue` arguments of the function and send the 
+  `variables` and `operationName` arguments that are related to the query request.


This:

You send empty objects to the rootValue and contextValue arguments of the function

Loses me. I get the second part of the sentence about variables and operationName but where is the first part happening in the code? It may be as simple as saying:

You send empty objects to the rootValue and contextValue arguments of the function with X and Y respectively.

X and Y being code snippets like {} or whatever is actually doing it.

ohh I thought that empty objects are enough.
Ok changed the whole sentence, let me know what you think

kapunahelewong · 2017-02-07T16:36:31Z

public/docs/ts/latest/cookbook/graphql.jade

+  You send empty objects to the `rootValue` and `contextValue` arguments of the function and send the 
+  `variables` and `operationName` arguments that are related to the query request.
+
+  Now export the new `InBrowserNetworkInterface` class in order to import it to Apollo Client.


Now -> Lastly

This lets them know we are at the end of covering what's happening in this code snippet.

kapunahelewong · 2017-02-07T16:38:14Z

public/docs/ts/latest/cookbook/graphql.jade

+  :marked
+    Uri: Let's add a conclusion showing what was accomplished in the doc. 
+    Maybe something like (please add anything I've missed):
+    :Kapunahele - done, but not sure if its enough?


Let's save the details about the conclusion for when we have finalized everything. Then we can make sure it has everything in the same way we are planning for the table of contents.

kapunahelewong · 2017-02-10T16:14:06Z

public/docs/ts/latest/cookbook/graphql.jade

+<a id="top"></a>
+:marked
+  GraphQL is a network protocol, a query language for your API and a runtime for fulfilling those queries with your existing data.
+


kapunahelewong · 2017-02-10T16:23:22Z

public/docs/ts/latest/cookbook/graphql.jade

+
+.l-sub-section
+  :marked
+    You can think about it as a replacement/enhancement for REST (but you can use them both alongside each other).


I've been thinking about this one for a while but only just now came up with this:

GraphQL is a replacement or enhancement for REST and can be used in conjunction with it.

Much better! done.

kapunahelewong · 2017-02-10T16:35:41Z

public/docs/ts/latest/cookbook/graphql.jade

+:marked
+  ## What is GraphQL?
+
+  GraphQL is an API query language, helping your Angular app to:


kapunahelewong · 2017-02-10T16:36:13Z

public/docs/ts/latest/cookbook/graphql.jade

+
+  GraphQL is an API query language, helping your Angular app to:
+
+  - Fetch exactly the information it needs from your server.


your server -> the server

kapunahelewong · 2017-02-10T16:40:38Z

public/docs/ts/latest/cookbook/graphql.jade

+  NoSql, REST, Queues, .NET servers, Java servers or any other technology or data source.
+  - GraphQL solves the need of sending multiple requests for multiple resources to the server and
+  then running complex joins on the client&mdash;without the need to create a custom endpoint like REST does.
+  - The GraphQL spec also includes protocols for real-time push updates from the server to the client.


Please search for and update spec -> specification and docs -> documentation.

kapunahelewong · 2017-02-10T20:26:11Z

public/docs/ts/latest/cookbook/graphql.jade

+
+  Apollo's `mutate` function returns the result as an Observable.
+  The Observable returns a `mutationResult` variable that is structured 
+  like the `ApolloQueryResult` TypeScript Type, where the generic `T` type is a `Hero` type:


Type -> type

kapunahelewong · 2017-02-10T20:27:21Z

public/docs/ts/latest/cookbook/graphql.jade

+  };
+:marked
+  If this looks familiar, it's because that's also how you reference the `mutationResult` variable in TypeScript.
+  To access the hero data `mutationResult` returns, use dot notation to traverse `mutationResult` and assign it to a new hero object.


object. --> object:

It seems like it would flow better with a semicolon.

kapunahelewong · 2017-02-10T20:28:38Z

public/docs/ts/latest/cookbook/graphql.jade

+  To access the hero data `mutationResult` returns, use dot notation to traverse `mutationResult` and assign it to a new hero object.
+makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'access-mutation-result', 'heroes.component.ts')
+:marked
+  Once you have created the new object with the data, push it into the `heroes` array.


~~Once~~ --> "Now that..."

kapunahelewong · 2017-02-10T20:29:37Z

public/docs/ts/latest/cookbook/graphql.jade

+  Once you have created the new object with the data, push it into the `heroes` array.
+
+:marked
+  Just like a query, the mutate function returns an Observable you can subscribe to 


mutate --> mutate

(Please put in code font).

kapunahelewong · 2017-02-10T20:30:57Z

public/docs/ts/latest/cookbook/graphql.jade

+  Just like a query, the mutate function returns an Observable you can subscribe to 
+  that handles the data you request.
+
+  At this point, your existing heroes app can also add a hero:


~~At this point~~

~~also~~

Now your existing heroes app can add a hero using GraphQL.

googlebot · 2017-03-18T13:49:12Z

CLAs look good, thanks!

googlebot · 2017-03-18T13:49:13Z

CLAs look good, thanks!

kapunahelewong

Was only able to get to line 227. Very simple changes. Will have to return to continue.

kapunahelewong · 2017-03-20T14:32:13Z

public/docs/ts/latest/cookbook/graphql.jade

+    GraphQL is a replacement or enhancement for REST and can be used in conjunction with it.
+
+:marked
+  GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.


Since these first three sentences start with "GraphQL", could we vary the language a little? Maybe one could start with "The GraphQL..." <--- I don't know what the right word would be there. In regular language, interface would work, but considering the context, we can't use that, right? Another way we could reduce repetition in the language could be by combining two of these sentences.

Maybe the first and third could be combined with the third starting with "It" instead. Then we leave the subsection immediately after.

kapunahelewong · 2017-03-20T14:35:12Z

public/docs/ts/latest/cookbook/graphql.jade

+  ## What is GraphQL?
+
+  GraphQL is an API query language, helping your Angular app:
+


~~, helping your Angular app:~~ --> "that helps your Angular app do the following:"

kapunahelewong · 2017-03-20T14:37:15Z

public/docs/ts/latest/cookbook/graphql.jade

+  - Merge multiple dependencies into one single response from the server.
+  - Handle server data dependency in a component structure.
+
+  It’s also important to understand that:


~~that~~ --> "three key points" or "these key points"

We want intros to lists to be complete sentences, rather than having the list items complete the sentence. I just recently came to understand that if you're wondering why I hadn't mentioned it before.

kapunahelewong · 2017-03-20T14:37:41Z

public/docs/ts/latest/cookbook/graphql.jade

+  It’s also important to understand that:
+
+  - **GraphQL is not a data source**. The GraphQL runtime works on top of any data source&mdash;SQL,
+  NoSql, REST, Queues, .NET servers, Java servers or any other technology or data source.


comma before or

kapunahelewong · 2017-03-20T14:40:00Z

public/docs/ts/latest/cookbook/graphql.jade

+
+  - **GraphQL is not a data source**. The GraphQL runtime works on top of any data source&mdash;SQL,
+  NoSql, REST, Queues, .NET servers, Java servers or any other technology or data source.
+  - GraphQL solves the need of sending multiple requests for multiple resources to the server and


Please remove one of the occurrences of "multiple" since they are close together. Does that still work? Is there another word we could use for the second one? Maybe "various"?

kapunahelewong · 2017-03-20T14:57:01Z

public/docs/ts/latest/cookbook/graphql.jade

+
+:marked
+  The `watchQuery` function tells the Apollo Client what data 
+  this component needs. The Apollo Client then returns the 


This is the first mention of the Apollo Client. We should add a phrase explaining in just a few words (to preserve brevity) what the Apollo Client is:

"....the Apollo Client, the x that lets you x, what data...."

or:
"....the Apollo Client, covered later,...."

kapunahelewong · 2017-03-20T14:57:56Z

public/docs/ts/latest/cookbook/graphql.jade

+  necessary data to the component as an Observable.
+  For example, adding an `age` field to the app is 
+  simple because you only change the component (you cover 
+  this syntax [later](#querying) in the cookbook) And then modify the template accordingly:


"And then modify" --> "and then modify".

kapunahelewong · 2017-03-20T15:08:33Z

public/docs/ts/latest/cookbook/graphql.jade

+
+:marked
+  That might work for simple cases but the problem here is that `getHeroes` might fetch
+  more information than the app really needs for each hero.


~~the problem here is that~~ --> but as your app grows

kapunahelewong · 2017-03-20T15:11:37Z

public/docs/ts/latest/cookbook/graphql.jade

+    and migrate gradually from them.
+
+:marked
+  ### Typed API, tooling and auto documentation


please put a comma after and

kapunahelewong · 2017-03-20T15:15:28Z

public/docs/ts/latest/cookbook/graphql.jade

+    The full documentation can be found on the [Apollo Client website](http://dev.apollodata.com/).
+
+:marked
+  The starting point for the app is the [Tour of Heroes tutorial](https://github.com/Urigo/quickstart/archive/graphql-start.zip) app at its end state.


This is helpful, but we can't rely on third party for the download. We should change this to the live example/downloadable example of the TOH.

googlebot · 2017-03-20T17:07:31Z

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that they're okay with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

googlebot · 2017-03-20T17:07:31Z

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that they're okay with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

kamilkisiela · 2017-03-22T08:04:45Z

@googlebot I signed it

kapunahelewong · 2017-03-27T19:36:15Z

FYI, I have to switch gears for a little bit, but will be back to work on this PR. Looking forward to seeing this cookbook in the docs!

Use ISubscription because this from Apollo is not compatible with that from RxJS

…ill look nice

…cript now

googlebot added the CLA: yes label Jan 25, 2017

Urigo closed this Jan 25, 2017

Urigo reopened this Jan 25, 2017

Urigo force-pushed the graphql-cookbook branch 2 times, most recently from c03df74 to 6d7fa3f Compare February 3, 2017 05:31

Urigo mentioned this pull request Feb 6, 2017

Integrating angular2-apollo into the Angular2 quickstart project the-guild-org/apollo-angular#23

Closed

googlebot added CLA: no and removed CLA: yes labels Feb 7, 2017

kapunahelewong reviewed Feb 7, 2017

View reviewed changes

Urigo force-pushed the graphql-cookbook branch from 9f25ae5 to 20b9f66 Compare February 11, 2017 19:51

kapunahelewong reviewed Feb 13, 2017

View reviewed changes

Urigo force-pushed the graphql-cookbook branch 2 times, most recently from 01b6e27 to 3ebfe5a Compare February 20, 2017 22:51

Urigo force-pushed the graphql-cookbook branch from 3ebfe5a to bf9df6e Compare March 18, 2017 13:49

googlebot added CLA: yes and removed CLA: no labels Mar 18, 2017

Urigo force-pushed the graphql-cookbook branch 3 times, most recently from 99d2a5a to 1d1d352 Compare March 20, 2017 10:46

kapunahelewong suggested changes Mar 20, 2017

View reviewed changes

googlebot added CLA: no and removed CLA: yes labels Mar 20, 2017

Urigo force-pushed the graphql-cookbook branch from 301f6cb to 4ffd51f Compare March 21, 2017 23:42

Urigo force-pushed the graphql-cookbook branch from c405306 to 271074f Compare March 26, 2017 11:59

Urigo and others added 16 commits April 3, 2017 16:24

docs(graphql-cookbook): Complete GraphQL cookbook

a838859

docs(graphql-cookbook): Update dependencies

027b602

Use ISubscription because this from Apollo is not compatible with that from RxJS

docs(graphql-cookbook): Add a downloadable starter example

0088d67

docs(graphql-cookbook): Add Mocked network interface

6a6b881

docs(graphql-cookbook): Add Appendix about mocking a server

76f79f2

docs(graphql-cookbook): Fix @kapunahelewong review

e562ba8

docs(graphql-cookbook): Update headers for tests

66c2e78

docs(graphql-cookbook): Fix inner property value

16f9c85

docs(graphql-cookbook): Fix lint errors

0454030

docs(graphql-cookbook): Add the old in-memory-data just so the file w…

7158650

…ill look nice

docs(graphql-cookbook): Update Apollo Client

8609ea4

docs(graphql-cookbook): Add the GraphQL tag

52b0f05

docs(graphql-cookbook): Add dist files to AOT bundle

11b4f08

docs(graphql-cookbook): Add extra systemjs config to starter

916a734

docs(graphql-cookbook): Update @types/lodash because we use new TypeS…

851cf07

…cript now

docs(graphql-cookbook): Update to latest Apollo-Client

f85548a

Urigo force-pushed the graphql-cookbook branch from 4330ad9 to f85548a Compare April 3, 2017 23:41


		GraphQL is an API query language, helping your Angular app to:

		- Fetch exactly the information it needs from your server.

		## What is GraphQL?

		GraphQL is an API query language, helping your Angular app:

Conversation

Urigo commented Jan 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kamilkisiela commented Jan 26, 2017

Uh oh!

DxCx commented Jan 26, 2017

Uh oh!

alonp99 commented Jan 29, 2017

Uh oh!

Urigo commented Feb 3, 2017

Uh oh!

Urigo commented Feb 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

googlebot commented Feb 7, 2017

Uh oh!

googlebot commented Feb 7, 2017

Uh oh!

kapunahelewong left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Urigo commented Jan 25, 2017 •

edited

Loading

Urigo commented Feb 3, 2017 •

edited

Loading